home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nspr / prcountr.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  17KB  |  558 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Netscape Portable Runtime (NSPR).
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998-2000
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. #ifndef prcountr_h___
  39. #define prcountr_h___
  40.  
  41. /*----------------------------------------------------------------------------
  42. ** prcountr.h -- NSPR Instrumentation counters
  43. **
  44. ** The NSPR Counter Feature provides a means to "count
  45. ** something." Counters can be dynamically defined, incremented,
  46. ** decremented, set, and deleted under application program
  47. ** control.
  48. **                                                                                    
  49. ** The Counter Feature is intended to be used as instrumentation,                  
  50. ** not as operational data. If you need a counter for operational                  
  51. ** data, use native integral types.                                                
  52. **                                                                                    
  53. ** Counters are 32bit unsigned intergers. On overflow, a counter                   
  54. ** will wrap. No exception is recognized or reported.                              
  55. **                                                                                 
  56. ** A counter can be dynamically created using a two level naming
  57. ** convention. A "handle" is returned when the counter is
  58. ** created. The counter can subsequently be addressed by its
  59. ** handle. An API is provided to get an existing counter's handle
  60. ** given the names with  which it was originally created. 
  61. ** Similarly, a counter's name can be retrieved given its handle.
  62. ** 
  63. ** The counter naming convention is a two-level hierarchy. The
  64. ** QName is the higher level of the hierarchy; RName is the
  65. ** lower level. RNames can be thought of as existing within a
  66. ** QName. The same RName can exist within multiple QNames. QNames
  67. ** are unique. The NSPR Counter is not a near-zero overhead
  68. ** feature. Application designers should be aware of 
  69. ** serialization issues when using the Counter API. Creating a
  70. ** counter locks a large asset, potentially causing a stall. This
  71. ** suggest that applications should create counters at component
  72. ** initialization, for example, and not create and destroy them
  73. ** willy-nilly. ... You have been warned.
  74. ** 
  75. ** Incrementing and Adding to counters uses atomic operations.
  76. ** The performance of these operations will vary from platform
  77. ** to platform. On platforms where atomic operations are not
  78. ** supported the overhead may be substantial.
  79. ** 
  80. ** When traversing the counter database with FindNext functions,
  81. ** the instantaneous values of any given counter is that at the
  82. ** moment of extraction. The state of the entire counter database
  83. ** may not be viewed as atomic.
  84. ** 
  85. ** The counter interface may be disabled (No-Op'd) at compile
  86. ** time. When DEBUG is defined at compile time, the Counter
  87. ** Feature is compiled into NSPR and applications invoking it.
  88. ** When DEBUG is not defined, the counter macros compile to
  89. ** nothing. To force the Counter Feature to be compiled into an
  90. ** optimized build, define FORCE_NSPR_COUNTERS at compile time
  91. ** for both NSPR and the application intending to use it.
  92. ** 
  93. ** Application designers should use the macro form of the Counter
  94. ** Feature methods to minimize performance impact in optimized
  95. ** builds. The macros normally compile to nothing on optimized
  96. ** builds.
  97. ** 
  98. ** Application designers should be aware of the effects of
  99. ** debug and optimized build differences when using result of the
  100. ** Counter Feature macros in expressions.
  101. ** 
  102. ** The Counter Feature is thread-safe and SMP safe.
  103. ** 
  104. ** /lth. 09-Jun-1998.
  105. */
  106.  
  107. #include "prtypes.h"
  108.  
  109. PR_BEGIN_EXTERN_C
  110.  
  111. /*
  112. ** Opaque counter handle type.
  113. ** ... don't even think of looking in here.
  114. **
  115. */
  116. typedef void *  PRCounterHandle;
  117.  
  118. #define PRCOUNTER_NAME_MAX 31
  119. #define PRCOUNTER_DESC_MAX 255
  120.  
  121.  
  122.  
  123. /* -----------------------------------------------------------------------
  124. ** FUNCTION: PR_DEFINE_COUNTER() -- Define a PRCounterHandle
  125. ** 
  126. ** DESCRIPTION: PR_DEFINE_COUNTER() is used to define a counter
  127. ** handle.
  128. ** 
  129. */
  130. #define PR_DEFINE_COUNTER(name) PRCounterHandle name
  131.  
  132. /* -----------------------------------------------------------------------
  133. ** FUNCTION: PR_INIT_COUNTER_HANDLE() -- Set the value of a PRCounterHandle
  134. ** 
  135. ** DESCRIPTION: 
  136. ** PR_INIT_COUNTER_HANDLE() sets the value of a PRCounterHandle
  137. ** to value.
  138. ** 
  139. */
  140. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  141. #define PR_INIT_COUNTER_HANDLE(handle,value)\
  142.     (handle) = (PRCounterHandle)(value)
  143. #else
  144. #define PR_INIT_COUNTER_HANDLE(handle,value)
  145. #endif
  146.  
  147. /* -----------------------------------------------------------------------
  148. ** FUNCTION: PR_CreateCounter() -- Create a counter
  149. ** 
  150. ** DESCRIPTION: PR_CreateCounter() creates a counter object and
  151. ** initializes it to zero.
  152. ** 
  153. ** The macro form takes as its first argument the name of the
  154. ** PRCounterHandle to receive the handle returned from
  155. ** PR_CreateCounter().
  156. ** 
  157. ** INPUTS:
  158. **  qName: The QName for the counter object. The maximum length
  159. ** of qName is defined by PRCOUNTER_NAME_MAX
  160. ** 
  161. **  rName: The RName for the counter object. The maximum length
  162. ** of qName is defined by PRCOUNTER_NAME_MAX
  163. ** 
  164. **  descrioption: The description of the counter object. The
  165. ** maximum length of description is defined by
  166. ** PRCOUNTER_DESC_MAX.
  167. ** 
  168. ** OUTPUTS:
  169. ** 
  170. ** RETURNS:
  171. **  PRCounterHandle.
  172. ** 
  173. ** RESTRICTIONS:
  174. ** 
  175. */
  176. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  177. #define PR_CREATE_COUNTER(handle,qName,rName,description)\
  178.    (handle) = PR_CreateCounter((qName),(rName),(description))
  179. #else
  180. #define PR_CREATE_COUNTER(handle,qName,rName,description)
  181. #endif
  182.  
  183. NSPR_API(PRCounterHandle) 
  184.     PR_CreateCounter( 
  185.         const char *qName, 
  186.         const char *rName, 
  187.         const char *description 
  188. );
  189.  
  190. /* -----------------------------------------------------------------------
  191. ** FUNCTION: PR_DestroyCounter() -- Destroy a counter object.
  192. ** 
  193. ** DESCRIPTION: PR_DestroyCounter() removes a counter and
  194. ** unregisters its handle from the counter database.
  195. ** 
  196. ** INPUTS:
  197. **  handle: the PRCounterHandle of the counter to be destroyed.
  198. ** 
  199. ** OUTPUTS: 
  200. **  The counter is destroyed.
  201. ** 
  202. ** RETURNS: void
  203. ** 
  204. ** RESTRICTIONS:
  205. ** 
  206. */
  207. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  208. #define PR_DESTROY_COUNTER(handle) PR_DestroyCounter((handle))
  209. #else
  210. #define PR_DESTROY_COUNTER(handle)
  211. #endif
  212.  
  213. NSPR_API(void) 
  214.     PR_DestroyCounter( 
  215.         PRCounterHandle handle 
  216. );
  217.  
  218.  
  219. /* -----------------------------------------------------------------------
  220. ** FUNCTION: PR_GetCounterHandleFromName() -- Retreive a
  221. ** counter's handle give its name.
  222. ** 
  223. ** DESCRIPTION: PR_GetCounterHandleFromName() retreives a
  224. ** counter's handle from the counter database, given the name
  225. ** the counter was originally created with.
  226. ** 
  227. ** INPUTS:
  228. **  qName: Counter's original QName.
  229. **  rName: Counter's original RName.
  230. ** 
  231. ** OUTPUTS:
  232. ** 
  233. ** RETURNS: 
  234. **  PRCounterHandle or PRCounterError.
  235. ** 
  236. ** RESTRICTIONS:
  237. ** 
  238. */
  239. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  240. #define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)\
  241.     (handle) = PR_GetCounterHandleFromName((qName),(rName))
  242. #else
  243. #define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)
  244. #endif
  245.  
  246. NSPR_API(PRCounterHandle) 
  247.     PR_GetCounterHandleFromName( 
  248.         const char *qName, 
  249.         const char *rName 
  250. );
  251.  
  252. /* -----------------------------------------------------------------------
  253. ** FUNCTION: PR_GetCounterNameFromHandle() -- Retreive a
  254. ** counter's name, given its handle.
  255. ** 
  256. ** DESCRIPTION: PR_GetCounterNameFromHandle() retreives a
  257. ** counter's name given its handle.
  258. ** 
  259. ** INPUTS:
  260. **  qName: Where to store a pointer to qName.
  261. **  rName: Where to store a pointer to rName.
  262. **  description: Where to store a pointer to description.
  263. ** 
  264. ** OUTPUTS: Pointers to the Counter Feature's copies of the names
  265. ** used when the counters were created.
  266. ** 
  267. ** RETURNS: void
  268. ** 
  269. ** RESTRICTIONS:
  270. ** 
  271. */
  272. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  273. #define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description)\
  274.     PR_GetCounterNameFromHandle((handle),(qName),(rName),(description))
  275. #else
  276. #define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description )
  277. #endif
  278.  
  279. NSPR_API(void) 
  280.     PR_GetCounterNameFromHandle( 
  281.         PRCounterHandle handle,  
  282.         const char **qName, 
  283.         const char **rName, 
  284.         const char **description 
  285. );
  286.  
  287.  
  288. /* -----------------------------------------------------------------------
  289. ** FUNCTION: PR_IncrementCounter() -- Add one to the referenced
  290. ** counter.
  291. ** 
  292. ** DESCRIPTION: Add one to the referenced counter.
  293. ** 
  294. ** INPUTS:
  295. **  handle: The PRCounterHandle of the counter to be incremented
  296. ** 
  297. ** OUTPUTS: The counter is incrementd.
  298. ** 
  299. ** RETURNS: void
  300. ** 
  301. ** RESTRICTIONS:
  302. ** 
  303. */
  304. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  305. #define PR_INCREMENT_COUNTER(handle) PR_IncrementCounter(handle)
  306. #else
  307. #define PR_INCREMENT_COUNTER(handle)
  308. #endif
  309.  
  310. NSPR_API(void) 
  311.     PR_IncrementCounter( 
  312.         PRCounterHandle handle
  313. );
  314.  
  315.  
  316. /* -----------------------------------------------------------------------
  317. ** FUNCTION: PR_DecrementCounter() -- Subtract one from the
  318. ** referenced counter
  319. ** 
  320. ** DESCRIPTION: Subtract one from the referenced counter.
  321. ** 
  322. ** INPUTS: 
  323. **  handle: The PRCounterHandle of the coutner to be
  324. ** decremented.
  325. ** 
  326. ** OUTPUTS: the counter is decremented.
  327. ** 
  328. ** RETURNS: void
  329. ** 
  330. ** RESTRICTIONS:
  331. ** 
  332. */
  333. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  334. #define PR_DECREMENT_COUNTER(handle) PR_DecrementCounter(handle)
  335. #else
  336. #define PR_DECREMENT_COUNTER(handle)
  337. #endif
  338.  
  339. NSPR_API(void) 
  340.     PR_DecrementCounter( 
  341.         PRCounterHandle handle
  342. );
  343.  
  344. /* -----------------------------------------------------------------------
  345. ** FUNCTION: PR_AddToCounter() -- Add a value to a counter.
  346. ** 
  347. ** DESCRIPTION: Add value to the counter referenced by handle.
  348. ** 
  349. ** INPUTS:
  350. **  handle: the PRCounterHandle of the counter to be added to.
  351. ** 
  352. **  value: the value to be added to the counter.
  353. ** 
  354. ** OUTPUTS: new value for counter.
  355. ** 
  356. ** RETURNS: void
  357. ** 
  358. ** RESTRICTIONS:
  359. ** 
  360. */
  361. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  362. #define PR_ADD_TO_COUNTER(handle,value)\
  363.     PR_AddToCounter((handle),(value))
  364. #else
  365. #define PR_ADD_TO_COUNTER(handle,value)
  366. #endif
  367.  
  368. NSPR_API(void) 
  369.     PR_AddToCounter( 
  370.         PRCounterHandle handle, 
  371.         PRUint32 value 
  372. );
  373.  
  374.  
  375. /* -----------------------------------------------------------------------
  376. ** FUNCTION: PR_SubtractFromCounter() -- A value is subtracted
  377. ** from a counter.
  378. ** 
  379. ** DESCRIPTION:
  380. ** Subtract a value from a counter.
  381. ** 
  382. ** INPUTS:
  383. **  handle: the PRCounterHandle of the counter to be subtracted
  384. ** from.
  385. ** 
  386. **  value: the value to be subtracted from the counter.
  387. ** 
  388. ** OUTPUTS: new value for counter
  389. ** 
  390. ** RETURNS: void
  391. ** 
  392. ** RESTRICTIONS:
  393. ** 
  394. */
  395. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  396. #define PR_SUBTRACT_FROM_COUNTER(handle,value)\
  397.     PR_SubtractFromCounter((handle),(value))
  398. #else
  399. #define PR_SUBTRACT_FROM_COUNTER(handle,value)
  400. #endif
  401.  
  402. NSPR_API(void) 
  403.     PR_SubtractFromCounter( 
  404.         PRCounterHandle handle, 
  405.         PRUint32 value 
  406. );
  407.  
  408.  
  409. /* -----------------------------------------------------------------------
  410. ** FUNCTION: PR_GetCounter() -- Retreive the value of a counter
  411. ** 
  412. ** DESCRIPTION:
  413. ** Retreive the value of a counter.
  414. ** 
  415. ** INPUTS:
  416. **  handle: the PR_CounterHandle of the counter to be retreived
  417. ** 
  418. ** OUTPUTS:
  419. ** 
  420. ** RETURNS: The value of the referenced counter
  421. ** 
  422. ** RESTRICTIONS:
  423. ** 
  424. */
  425. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  426. #define PR_GET_COUNTER(counter,handle)\
  427.     (counter) = PR_GetCounter((handle))
  428. #else
  429. #define PR_GET_COUNTER(counter,handle) 0
  430. #endif
  431.  
  432. NSPR_API(PRUint32) 
  433.     PR_GetCounter( 
  434.         PRCounterHandle handle 
  435. );
  436.  
  437. /* -----------------------------------------------------------------------
  438. ** FUNCTION: PR_SetCounter() -- Replace the content of counter
  439. ** with value.
  440. ** 
  441. ** DESCRIPTION: The contents of the referenced counter are
  442. ** replaced by value.
  443. ** 
  444. ** INPUTS:
  445. **  handle: the PRCounterHandle of the counter whose contents
  446. ** are to be replaced.
  447. ** 
  448. **  value: the new value of the counter.
  449. ** 
  450. ** OUTPUTS:
  451. ** 
  452. ** RETURNS: void
  453. ** 
  454. ** RESTRICTIONS:
  455. ** 
  456. */
  457. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  458. #define PR_SET_COUNTER(handle,value) PR_SetCounter((handle),(value))
  459. #else
  460. #define PR_SET_COUNTER(handle,value)
  461. #endif
  462.  
  463. NSPR_API(void) 
  464.     PR_SetCounter( 
  465.         PRCounterHandle handle, 
  466.         PRUint32 value 
  467. );
  468.  
  469.  
  470. /* -----------------------------------------------------------------------
  471. ** FUNCTION: PR_FindNextCounterQname() -- Retreive the next QName counter
  472. ** handle iterator
  473. ** 
  474. ** DESCRIPTION:
  475. ** PR_FindNextCounterQname() retreives the first or next Qname
  476. ** the counter data base, depending on the value of handle. When
  477. ** handle is NULL, the function attempts to retreive the first
  478. ** QName handle in the database. When handle is a handle previosly
  479. ** retreived QName handle, then the function attempts to retreive
  480. ** the next QName handle.
  481. ** 
  482. ** INPUTS: 
  483. **  handle: PRCounterHandle or NULL.
  484. ** 
  485. ** OUTPUTS: returned
  486. ** 
  487. ** RETURNS: PRCounterHandle or NULL when no more QName counter
  488. ** handles are present.
  489. ** 
  490. ** RESTRICTIONS:
  491. **  A concurrent PR_CreateCounter() or PR_DestroyCounter() may
  492. ** cause unpredictable results.
  493. ** 
  494. ** A PRCounterHandle returned from this function may only be used
  495. ** in another PR_FindNextCounterQname() function call; other
  496. ** operations may cause unpredictable results.
  497. ** 
  498. */
  499. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  500. #define PR_FIND_NEXT_COUNTER_QNAME(next,handle)\
  501.     (next) = PR_FindNextCounterQname((handle))
  502. #else
  503. #define PR_FIND_NEXT_COUNTER_QNAME(next,handle) NULL
  504. #endif
  505.  
  506. NSPR_API(PRCounterHandle) 
  507.     PR_FindNextCounterQname( 
  508.         PRCounterHandle handle
  509. );
  510.  
  511. /* -----------------------------------------------------------------------
  512. ** FUNCTION: PR_FindNextCounterRname() -- Retreive the next RName counter
  513. ** handle iterator
  514. ** 
  515. ** DESCRIPTION:
  516. ** PR_FindNextCounterRname() retreives the first or next RNname
  517. ** handle from the counter data base, depending on the
  518. ** value of handle. When handle is NULL, the function attempts to
  519. ** retreive the first RName handle in the database. When handle is
  520. ** a handle previosly retreived RName handle, then the function
  521. ** attempts to retreive the next RName handle.
  522. ** 
  523. ** INPUTS:
  524. **  handle: PRCounterHandle or NULL.
  525. **  qhandle: PRCounterHandle of a previously aquired via
  526. ** PR_FIND_NEXT_QNAME_HANDLE()
  527. ** 
  528. ** OUTPUTS: returned
  529. ** 
  530. ** RETURNS: PRCounterHandle or NULL when no more RName counter
  531. ** handles are present.
  532. ** 
  533. ** RESTRICTIONS:
  534. **  A concurrent PR_CreateCounter() or PR_DestroyCounter() may
  535. ** cause unpredictable results.
  536. ** 
  537. ** A PRCounterHandle returned from this function may only be used
  538. ** in another PR_FindNextCounterRname() function call; other
  539. ** operations may cause unpredictable results.
  540. ** 
  541. */
  542. #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
  543. #define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)\
  544.     (next) = PR_FindNextCounterRname((rhandle),(qhandle))
  545. #else
  546. #define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)
  547. #endif
  548.  
  549. NSPR_API(PRCounterHandle) 
  550.     PR_FindNextCounterRname( 
  551.         PRCounterHandle rhandle,
  552.         PRCounterHandle qhandle
  553. );
  554.  
  555. PR_END_EXTERN_C
  556.  
  557. #endif /* prcountr_h___ */
  558.